home *** CD-ROM | disk | FTP | other *** search
Text File | 1999-08-24 | 17.2 KB | 440 lines | [ TEXT/ttxt]
*** *** Universal Serial Bus(tm) (USB) for the Mac OS *** Mac OS USB 1.3 DDK Developer Release Notes *** Copyright 1998 Apple Computer, Inc. *** *** IMPORTANT *** IMPORTANT *** IMPORTANT *** IMPORTANT *** The USB Support and USB Device Extension files may not be distributed in any manner. These files are for developer use only, and are NOT TO BE INCLUDED with the components installed with your product. Table of Contents: ------------------------------------------------------------- Changes from USB v1.0, 1.0.1, 1.1, 1.2 -> 1.3f3 System Requirements for USB 1.3f3 USB Fundamentals Keeping up to date on Mac OS USB Getting started with Mac OS USB Installing the Mac OS USB Software Using the Mac OS USB DDK under MPW Using the Mac OS USB DDK with MetroWerks CodeWarrior Installing the Mac OS USB DDK for CodeWarrior for the First Time Updating a Previously Installed Mac OS USB DDK for CodeWarrior Using the CodeWarrior Project Files Description of Installed Files Known Problems and Issues Contact Information ------------------------------------------------------------- Changes from USB v1.0, 1.0.1, 1.1, 1.2 -> 1.3f3 ------------------------------------------- Refer to the document "Mac OS USB v1.3f3 Readme" for a description of the changes between versions of USB. System Requirements for USB 1.3 ------------------------------- Apple is formally qualifying USB 1.3 on the Macintosh systems with built-in USB and SSW 8.6 installed. To test with USB v1.3f3, first install SSW 8.6 onto a system with USB Built-in then follow the instructions below. You can access the US version of the update with the following URL. >http://download.info.apple.com/Apple_Support_Area/Apple_Software_Updates/US/Macintosh/System/Mac_OS_8.6_Update/> If your product depends on USB v1.2 for Isochronous support, you should have your Installer check for the presence of this release of USB using the Gestalt function with the gestaltUSBVersion selector. This selector value is defined in the Gestalt.h header file which is part of the Universal Interfaces and Libraries v3.2. Refer to the Mac OS USB Developer web site for information on how customers can upgrade to this version of USB. <http://developer.apple.com/hardware/usb/devinfo.htm> USB Fundamentals ---------------- For the current generation of Power Macintosh systems, USB is the primary interface for connections to low to medium speed peripheral devices. There are numerous advantages for adopting the USB standard on Macintosh, and they are discussed in the "Mac OS USB DDK API Reference Guide". On the future Macintosh systems there will be no ADB, Serial Port, or SCSI connections. USB will be the primary port for connecting peripheral devices to the Macintosh. The DDK provides the tools, interfaces, system files, and module examples for you to start development of USB products for the Macintosh. The DDK provides the same release of USB component software that ships on the introductory release of the Power Macintosh iMac system. Keeping up to date on Mac OS USB -------------------------------- To stay abreast with developments on Mac OS USB, check out the Mac OS USB Developer web site for the latest information. As updates to Mac OS USB occur, development releases of the software will be made available from this web site. The URL for the web site is: <http://developer.apple.com/dev/usb> You can also subscribe to the Mac OS USB Developer mailing list where development questions regarding Mac OS USB are posed and answered. To submit a question to the mailing list you must first be a subscriber. To subscribe to the mailing list, send an email with the subject field set to "subscribe usb" (omit the double quotes for the message) to requests@isg.apple.com. Use the following URL to accomplish this. <mailto:requests@isg.apple.com?SUBJECT=subscribe usb> USB Alerts to developers are always posted to the mailing list. These alerts are also posted to the Mac OS USB Developer Web site at the following location. http://developer.apple.com/dev/usb/devalerts.html Getting started with Mac OS USB ------------------------------- To develop with Mac OS USB v1.3, you will need a Power Macintosh system with USB built in, or a USB PCI card installed. You should also have SSW 8.6 installed. USB v1.3 will support PCI USB cards from several vendors. The enclosed software is for developmental purposes and will support USB PCI cards from other vendors, but it is not directly supported by Apple, nor is it intended for end-users. End-user customers are encouraged to purchase a PCI USB card that includes licensed software and support. You may find that development on a Power Mac system with a USB PCI card and serial port, is easier, as you can use the Power Mac Debugger with a second Power Macintosh system. A Power Macintosh system with ADBkeyboard is useful for debugging with Macsbug, since there are cases when the system cannot process keystrokes from a USB keyboard. Installing the Mac OS USB Software ---------------------------------- Before using the enclosed software on an iMac or 1999 Power Macintosh G3, you must already have the Mac OS USB v1.1 present. If the Mac OS ROM file includes this release of USB, do not install the system extension components from this DDK to the Extensions Folder. To install the USB System Software components, 1. remove all files with the following names from your Extensions Folder, USB Support, USB Device Extension, USBCompositeDriver, USBFamilyExpert, USBHIDKeyboardModule, USBHIDMouseModule, USBHIDUniversalModule, USBHubDriver0, USBHubDriver1, and USBOpenHCIDriver USBPrintDriver USBCommClass SerialShimLib 2. drag copy the contents of the folder :USBDDK:Extensions-AppleBuilt: to the Extensions folder. 3. Before you reboot, modify the file "USB Support" to include a new resource 'usbx' (Resource ID = 1984). Without this resource, this release of USB will not load. The following alert is raised to indicate that the resource is not present. 4. Reboot your system after making this modification. Important Notes on Installation and Use of this DDK software ------------------------------------------------------------ This DDK will let you look at the sources to some working class drivers, build the examples, and develop & build your own code. Please remember that these driver samples are Copyright Apple Computer, Inc.. You may use the supplied code to develop Class Drivers for your devices. As for publishing the source code, please check first with the Mac OS USB DDK License agreement, included in this DDK. The current driver samples may, reflect the latest state of the art of driver writing for USB in the Mac OS. Note that the PrinterClassModule sample is for example purpose only. This sample is the basis for real drivers under development, however we are unable to provide the actual class driver code. The remaining examples are the real code for the Keyboard HID, Mouse HID, Universal HID, and Composite class drivers which will ship on the iMac While not extensively tested (by the development team), the sample sources have been tweaked slightly to make builds under CodeWarrior some what less problematic. The project files are provided to help jumpstart your development process. Using the Mac OS USB DDK under MPW ---------------------------------- For previous releases of the USB DDK, we provided a current UserStartup•USBDDK and makefiles for each of the sample class drivers. As there are very few developers who program with the MPW environment and to expidite the release of this DDK, we will no provide make files for the class driver samples, nor UserStartup files for MPW. If MPW is your primary development platform and you need a make file for one of the example class drivers, submit a request to the Mac OS USB mailing list and a sample make file, if available for the example, will be sent to you. See the section "Keeping up to date on Mac OS USB" above for information on how to subscribe to the Mac OS USB Developer mailing list. Using the Mac OS USB DDK with MetroWerks CodeWarrior --------------------------------------------------- We have supplied MetroWerks CodeWarrior project files for all of the USB Modules code examples. All of the project files were created using CodeWarrior Pro 1, IDE 2.0. The project files are also compatible with CodeWarrior Pro IDE 2.1, 3.0 and later. For the CodeWarrior IDE environments v2.0 - v3.0, you must use the Universal Interface & Libraries v3.1. The examples will not build using the interfaces supplied with the CodeWarrior v.2 - v3.0 environments. The URL for the Developer Development Kits web page is <http://developer.apple.com/sdk/> As mentioned for MPW, it is highly recommend that you use one Macintosh for coding purposes and one Mac (aka "Target" system) for checkout/testing purposes. The supplied project files will place the built drivers and extensions into the Target folder of the DDK. Installing the Mac OS USB DDK for CodeWarrior for the First Time ----------------------------------------------------------- 1. You can place the USBDDK anywhere on your development system for the CodeWarrior environment. The access paths for the project files are project and compiler relative. If you move the examples folders out of the DDK, you must fix the access paths so that the sources can be found. 2. Ensure that the CodeWarrior IDE environment has at least the Universal Interfaces and Libraries 3.1 installed. The download file from the DDK website includes instructions for upgrading your CodeWarrior environment. Note that if you upgrade your interfaces, you will also need to upgrade your precompiled headers. The supplied CodeWarrior project files do not use precompiled headers. 3. Copy the USB.h file included in this SDK to the ":Mac OS Support:Headers:Universal Headers:" folder. 4. You will find that the project files will place the built drivers and extensions into the folder. "USBDDK:Extensions-MCWBuilt" If this folder does not exist, or the folder name is different, the class driver samples will be created in the CodeWarrior folder. Updating a Previously Installed Mac OS USB DDK for CodeWarrior ------------------------------------------------------------- 1. Copy the USB.h file included in this SDK to the ":Mac OS Support:Headers:Universal Headers:" folder. Do not use the USB.h header file from an earlier USB DDK with the supplied project files, as the examples may not build. 2. If you experience compiler errors with the program samples, check whether you have updated the USB.h header in the ":Mac OS Support:Headers:Universal Headers:" folder. 3. You will need to create a folder by the name "USBDDK:Extensions-MCWBuilt" If this folder does not exist, or the folder name is different, the class driver samples will be created in the CodeWarrior folder. Using the CodeWarrior Project Files --------------------------------- For the following samples, there is only a single target for each project: CompositeClassDriver KeyboardModule MouseModule UniversalModule USBKeypad USBModem USBTabletModule For the PrinterClassDriver example, compile the targets in the following order 1. PrinterClassDRVR - creates the 68K DRVR resource 2. PrintClassDriver - creates the USB PrintClassDriver module 3. ChooserPack.rsrc - creates the "PACK" resource 4. USB Chooser Driver - creates the Chooser extension for the USB printer For the USBSampleStorageDriver example, compile the targets in the following order 1. USBStorageClassDriver - creates the USB StorageClassDriver module 2. USBStorageClassShim - creates the shim module which loads the unit table driver when the device is attached USBStorageClassUTDriver - auto built into shim - native driver compiled as a resource into shim file. Description of Installed Files -------------------------- Files in the 'Extensions-AppleBuilt' folder: Files: Description: USB Device Extension File which contains the following class drivers USBCompositeDriver - A class driver which is loaded for class 0 & and subclass 0 devices (typically keyboards & mice, although a few printers & modems appear as composite class devices). USBHubDriver0 & USBHubDriver1 - The Hub driver for the root hub, the Apple USB keyboard's hub, and most 3rd party hubs. USBKeyboardModule - The HID Module loaded for a keyboard interface (typically in a compound device) USBMouseModule - A HID Module loaded for a mouse interface (typically in a compound device). USBHIDUniversalModule - A HID Module designed to support a number of 3rd party gaming devices via Game Sprockets. Refer to the "Mac OS USB Compatibility Notes" for a description of the game devices supported. USBOpenHCIDriver - The HAL (Hardware Abstraction Layer), also known as the "UIM" (USB Interface Module). This driver provides an abstracted interface to the OpenHCI host controllers on Mac motherboards and PCI controller cards. USB Support The INIT (actually an 'expt') portion of the Family Expert. Loaded prior to the INIT parade, it starts the 'find a USB bus (i.e. UIM driver), loads the hub driver (for the root hub), and starts the hub driver running. Once running, the hub driver locates devices attached to the port and asks the FamilyExpertLib to load drivers for the devices connected to the hub's ports. USBPrintDriver A Printing Class Driver for experimentation purposes. Printing WILL NOT be functional simply with the addition of this file. The chooser extension needed for USB printing is still in development and has not yet been released. Known Issues ------------ The following is a list of known issues with this final release of the USB DDK. - If you install this release of USB 1.3f3 directly without adding the 'usbx' (ID = 1984) resource, then USB will not load and an alert message is displayed Refer to the instructions above in section "Installing the Mac OS USB Software" on how to modify the "USB Support" file so that it will function correctly. - The USBSampleStorageDriver does not correctly demonstrate how to handle a hot unplug situation. This sample will be updated to demonstrate how this situation should be properly handled. The existing sample sets up a Timer Task which when fired makes a call to SystemTask. The call to SystemTask is not supported from an interrupt context. Contact Information ------------------- Mac OS USB DDK Upgrades and latest information: Check the Developer Development Kits web page for upgrades to the Mac OS USB DDK. The web page is <http://developer.apple.com/sdk/> For the latest information on Mac OS USB, check the Mac OS USB web page. The web page is <http://usb.apple.com> For Bug Reports: To ensure the appropriate data is collected, please use the Bug Reporter to send us your bug reports. The Bug Reporter can be found at: <http://developer.apple.com/bugreporter> When reporting problems, please include the machine configuration, including the vendor of the PCI USB card which you have tested with. For Technical Questions: For generic Mac OS USB questions, submit them to the Mac OS USB Developer mailing list. Refer to the section above "Keeping up to date on Mac OS USB" for information on how to subscribe to this mailing list. Often questions can be answered by someone on the mailing list. If your question is not answered on the mailing list, or if your question is proprietary, contact Worldwide Developer with purchased development-level technical support incidents at dts@apple.com Technical support incidents are bundled in our Premier and Select Developer programs. For information about joining our programs, please visit our Apple Developer Connection web site at http://developer.apple.com/programs. If you have never purchased a technical support incident and would like to find out how to do so, please visit the following site: http://developer.apple.com/programs/techsupport.html . Comments, Suggestions and Enhancement Requests Please send all comments and suggestions regarding the Mac OS USB DDK to usb@apple.com All email sent to this address will be read, however, we will not be to respond to all of your comments and suggestions. 
